<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Creating Indexes</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
    <link rel="home" href="index.html" title="Getting Started with Berkeley DB" />
    <link rel="up" href="persist_index.html" title="Chapter 4. Working with Indices" />
    <link rel="previous" href="persist_index.html" title="Chapter 4. Working with Indices" />
    <link rel="next" href="persist_access.html" title="Chapter 5. Saving and Retrieving Objects" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Creating Indexes</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="persist_index.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 4. Working with Indices</th>
          <td width="20%" align="right"> <a accesskey="n" href="persist_access.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="dplindexcreate"></a>Creating Indexes</h2>
          </div>
        </div>
        <div></div>
      </div>
      <p>
                  To create an index using the DPL, you use Java
                  annotations to declare which feature on the class is used
                  for the primary index, and which features (if any) are to
                  be used as secondary indexes.
          </p>
      <p>
                  All entity classes stored in the DPL must have a
                  primary index declared for it. 
          </p>
      <p>
                  Entity classes can have zero or more secondary
                  indexes declared for them. There is no limit on the
                  number of secondary indexes that you can declare.
          </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="dplprimaryidxdecl"></a>Declaring a Primary Indexes</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>
                          You declare a primary key for an entity class by
                          using the <tt class="literal">@PrimaryKey</tt>
                          annotation. This annotation must appear
                          immediately before the data member which
                          represents the class's primary key. For example:
                  </p>
        <pre class="programlisting">package persist.gettingStarted;

import com.sleepycat.persist.model.Entity;
import com.sleepycat.persist.model.PrimaryKey;

@Entity
public class Vendor {

    private String address;
    private String bizPhoneNumber;
    private String city;
    private String repName;
    private String repPhoneNumber;
    private String state;

    // Primary key is the vendor's name
    // This assumes that the vendor's name is
    // unique in the database.
    @PrimaryKey
    private String vendor;

    ... </pre>
        <p>
                            For this class, the <tt class="literal">vendor</tt> value is set for an individual
                            <tt class="classname">Vendor</tt> class object by
                            the <tt class="methodname">setVendorName()</tt>
                            method. If our example code fails to set this
                            value before storing the object, the data
                            member used to store the primary key is set to a
                            null value. This would result in a runtime
                            error.
                    </p>
        <p>
                            You can avoid the need to explicitly set a
                            value for a class's primary index by specifying
                            a sequence to be used for the primary key. This
                            results in an unique integer value being used
                            as the primary key for each stored object.
                    </p>
        <p>
                        You declare a sequence is to be used by specifying
                        the <tt class="literal">sequence</tt> keyword to the
                        <tt class="literal">@PrimaryKey</tt> annotation.
                        For example:
                    </p>
        <pre class="programlisting">@PrimaryKey(sequence="")
long myPrimaryKey; </pre>
        <p>
                        If you provide the <tt class="literal">sequence</tt> keyword with a name,
                        then the sequence is obtained from that named sequence.  For example:
                    </p>
        <pre class="programlisting">@PrimaryKey(sequence="Sequence_Namespace")
long myPrimaryKey; </pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="dplsecondaryidxdecl"></a>Declaring Secondary Indexes</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>
                        To declare a secondary index, we use the
                        <tt class="literal">@SecondaryKey</tt> annotation. Note
                        that when we do this, we must declare what sort of
                        an index it is; that is, what is its relationship to
                        other data in the data store.
                    </p>
        <p>
                        The <span class="emphasis"><em>kind</em></span> of indices that we
                        can declare are:
                    </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                                        <tt class="literal">ONE_TO_ONE</tt>
                                    </p>
              <p>
                                        This relationship indicates that
                                        the secondary key is unique to the
                                        object. If an object is stored with a
                                        secondary key that already
                                        exists in the data store, a run
                                        time error is raised.
                                    </p>
              <p>
                                        For example, a person object might
                                        be stored with a primary key of a
                                        social security number (in the US),
                                        with a secondary key of the
                                        person's employee number. Both
                                        values are expected to be unique in
                                        the data store.
                                    </p>
            </li>
            <li>
              <p>
                                        <tt class="literal">MANY_TO_ONE</tt>
                                    </p>
              <p>
                                        Indicates that the secondary key
                                        may be used for multiple
                                        objects in the data store. That is,
                                        the key appears more than
                                        once, but for each stored object it
                                        can be used only once.
                                    </p>
              <p>
                                        Consider a data store that relates
                                        managers to employees. A given
                                        manager will have multiple
                                        employees, but each employee is
                                        assumed to have just one manager.
                                        In this case, the manager's
                                        employee number might be a
                                        secondary key, so that you can
                                        quickly locate all the objects
                                        related to that manager's
                                        employees.
                                    </p>
            </li>
            <li>
              <p>
                                        <tt class="literal">ONE_TO_MANY</tt>
                                    </p>
              <p>
                                        Indicates that the secondary key
                                        might be used more than once for a
                                        given object. Index keys
                                        themselves are assumed to be
                                        unique, but multiple instances of
                                        the index can be used per object.
                                    </p>
              <p>
                                        For example, employees might have
                                        multiple unique email addresses. In
                                        this case, any given object can be
                                        access by one or more email
                                        addresses. Each such address is
                                        unique in the data store, but each
                                        such address will relate to a
                                        single employee object.
                                    </p>
            </li>
            <li>
              <p>
                                        <tt class="literal">MANY_TO_MANY</tt>
                                    </p>
              <p>
                                        There can be multiple keys for
                                        any given object, and for any given
                                        key there can be many related
                                        objects.
                                    </p>
              <p>
                                            For example, suppose your
                                            organization has a shared
                                            resource, such as printers. You
                                            might want to track which
                                            printers a given employee can
                                            use (there might be more than
                                            one). You might also want to
                                            track which employees can use a
                                            specific printer. This
                                            represents a many-to-many
                                            relationship.
                                    </p>
            </li>
          </ul>
        </div>
        <p>
                        Note that for <tt class="literal">ONE_TO_ONE</tt> and
                        <tt class="literal">MANY_TO_ONE</tt> relationships, you
                        need a simple data member (not an array or
                        collection) to hold the key. For
                        <tt class="literal">ONE_TO_MANY</tt> and
                        <tt class="literal">MANY_TO_MANY</tt> relationships, you
                        need an array or collection to hold the keys:
                    </p>
        <pre class="programlisting">@SecondaryKey(relate=ONE_TO_ONE)
private String primaryEmailAddress = new String();

@SecondaryKey(relate=ONE_TO_MANY)
private Set&lt;String&gt; emailAddresses = new HashSet&lt;String&gt;(); </pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="foreignkey"></a>Foreign Key Constraints</h3>
            </div>
          </div>
          <div></div>
        </div>
        <p>
                            Sometimes a secondary index is related in some
                            way to another entity class that is also
                            contained in the data store. That is, the
                            secondary key might be the primary key for
                            another entity class. If this is the case, you
                            can declare the foreign key constraint to make
                            data integrity easier to accomplish.
                         </p>
        <p>
                            For example, you might have one class that is
                            used to represent employees.
                            You might have another that is used to
                            represent corporate divisions. When you add or
                            modify an employee record, you might want to
                            ensure that the division to which the employee
                            belongs is known to the data store. You do this
                            by specifying a foreign key constraint.
                         </p>
        <p>
                            When a foreign key constraint is declared:
                         </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                                                 When a new secondary key
                                                 for the object is stored,
                                                 it is checked to make sure
                                                 it exists as a primary
                                                 key for the related
                                                 entity object. If it does
                                                 not, a runtime error
                                                 occurs.
                                         </p>
            </li>
            <li>
              <p>
                                                 When a related entity is
                                                 deleted (that is, a
                                                 corporate division is
                                                 removed from the data
                                                 store), some action is
                                                 automatically taken for
                                                 the entities that refer to
                                                 this object (that is, the
                                                 employee objects). Exactly
                                                 what that action is, is
                                                 definable by you. See
                                                 below.
                                         </p>
            </li>
          </ul>
        </div>
        <p>
                            When a related entity is deleted from the data
                            store, one of the following actions are taken:
                         </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                                                 <tt class="literal">ABORT</tt>
                                         </p>
              <p>
                                                The delete operation is not
                                                allowed. A runtime error is
                                                raised as a result of the
                                                operation. This is the
                                                default behavior.
                                         </p>
            </li>
            <li>
              <p>
                                                 <tt class="literal">CASCADE</tt>
                                         </p>
              <p>
                                            All entities related to this
                                            one are deleted as well. For
                                            example, if you deleted a
                                            <tt class="classname">Division</tt>
                                            object, then all
                                            <tt class="classname">Employee</tt>
                                            objects that belonged to the
                                            division are also deleted.
                                         </p>
            </li>
            <li>
              <p>
                                                 <tt class="literal">NULLIFY</tt>
                                         </p>
              <p>
                                            All entities related to the
                                            deleted entity are updated so
                                            that the pertinent data member
                                            is nullified. That is, if you
                                            deleted a division, then all
                                            employee objects related to
                                            that division would have their
                                            division key
                                            automatically set to null.
                                         </p>
            </li>
          </ul>
        </div>
        <p>
                            You declare a foreign key constraint by using
                            the <tt class="literal">relatedEntity</tt> keyword. You
                            declare the foreign key constraint deletion policy using the
                            <tt class="literal">onRelatedEntityDelete</tt> keyword. For
                            example, the following declares a foreign key
                            constraint to <tt class="classname">Division</tt>
                            class objects, and it causes related objects to
                            be deleted if the <tt class="classname">Division</tt>
                            class is deleted:
                         </p>
        <pre class="programlisting">@SecondaryKey(relate=ONE_TO_ONE, relatedEntity=Division.class, 
    onRelatedEntityDelete=CASCADE)
private String division = new String(); </pre>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="persist_index.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="persist_index.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="persist_access.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Chapter 4. Working with Indices </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Chapter 5. Saving and Retrieving Objects</td>
        </tr>
      </table>
    </div>
  </body>
</html>
